Describe new API related to triggers by serhiipylypchuk1991 · Pull Request #46 · DHTMLX/docs-richtext

serhiipylypchuk1991 · 2026-05-27T06:22:22Z

No description provided.

- new API reference page for the hide-suggest event - documents when the dropdown closes (selection, Escape, cursor leaves trigger, empty result)

- new API reference page for the insert-token event - documents callback fields (id, label, url, trigger, showTrigger)

- new API reference page for the show-suggest event - documents callback fields (trigger, query, items, pos) and intercept example

- new API reference page for the triggers property - covers static array, sync function, async function data sources - documents suggestion item fields and rendered token CSS targeting

- new API reference page for the triggerTemplate property - documents callback parameters (data, trigger) and template usage - includes tip on overriding the dropdown anchor width

- new guide covering trigger characters, data source forms, token rendering, and event handling - examples for static array, sync function, async function, and custom dropdown templates

- list hide-suggest, insert-token, and show-suggest in the events table

- list triggers and triggerTemplate in the properties table

- list triggers in the property overview with a link to the Mentions and tags guide

- update anchor in whats_new from #custom-toolbar-controls to #add-custom-toolbar-controls to match the heading in configuration.md

- add hide-suggest, insert-token, show-suggest under events - add triggers and trigger-template under properties - add mentions_and_tags under guides

kullias

the code changes somewhat in a side branch on custom actions, I added comments, for source code DM either me or the author of the code, we'll point to the branch

- add `action` field to triggers config with Custom action section (emoji insertion and slash-style command menu examples) - update insert-token event payload: id/label/url replaced by `data` object carrying the picked item plus custom fields; add `action` - note that `action` takes priority over `showTrigger` - show-suggest items now documented as optional fields + custom keys - extend mentions guide with custom action examples - fix typos, a broken anchor, and align wording across pages

- destructure ({ data, trigger, showTrigger }) to match the insert-token event docs and the PR review suggestion

DmitriySlabodchikov · 2026-06-03T16:10:12Z

+
+- `id` - (optional) unique identifier saved on the inserted token. If omitted, RichText generates an ID automatically
+- `label` - (required) the text shown in the dropdown and inserted into the document
+- `url` - (optional) URL associated with the item. RichText stores the inserted token URL as the `href` attribute.


ctrl-click to open this link

Done. The url field now notes that Ctrl+Click on the token opens the link.

DmitriySlabodchikov · 2026-06-03T16:15:04Z

+When a user selects an item in the dropdown, RichText inserts a non-editable token element into the document:
+
+~~~html {}
+<a data-token="@" data-token-id="alice" href="mailto:alice@example.com">@Alice</a>


Where:

@ is trigger

alice is id

mailto:alice@example.com is url

@Alice - combination of trigger and label, in case of showTrigger: false it would be just Alice

Done. Added a Where: breakdown under the token: @ → trigger (data-token), alice → id (data-token-id), mailto:alice@example.com → url (href), and @Alice → trigger + label (just Alice when showTrigger: false).

DmitriySlabodchikov · 2026-06-03T16:22:00Z

+
+#### Add emoji
+
+A common use case is inserting an emoji from a `:` trigger, where each item contains a custom `code` field. Pair `action` with [`triggerTemplate`](api/config/trigger-template.md) so the dropdown shows the emoji itself instead of just its label:


maybe it's better to use this snippet code with categories (it is also a good example of custom data filtering): https://snippet.dhtmlx.com/r16rmt4m

Done. Thanks for the snippet — added a new "Group emoji by category" section based on it: category headers (items with no code), custom data filtering that keeps only categories with matches, a triggerTemplate that renders headers in bold, and an api.intercept("insert-token", ...) guard so headers cannot be inserted. Kept the simpler "Add emoji" example above it as an intro.

DmitriySlabodchikov · 2026-06-03T16:25:08Z

+new richtext.Richtext("#root", {
+    triggers: [{ trigger: "@", data: people }],
+    triggerTemplate: template(obj => {
+        if (obj.trigger === "@") {


maybe add one more trigger, because otherwise there is no point in checking for equality to a "@"

Done. Added a second # trigger so the obj.trigger === "@" branch is actually meaningful, with the # dropdown falling back to the plain label.

DmitriySlabodchikov · 2026-06-03T16:27:15Z

+- `trigger` - the trigger character that opened the dropdown (`"@"`, `"#"`, etc.)
+
+:::tip
+The dropdown anchor has a fixed default width of `160px`. To make room for a wider template, override the width from a parent stylesheet (`!important` is needed because the widget sets the default via its own scoped CSS):


u can just make bit more complex css rule, like .wx-editor .wx-suggest-anchor instead of !important

Done. Replaced !important with the more specific .wx-editor .wx-suggest-anchor selector and updated the tip text to explain why the extra parent makes the rule win.

DmitriySlabodchikov · 2026-06-03T16:32:49Z

+Each item in the `data` object (or each item returned by a function) has the following fields:
+
+- `id` - (optional) unique identifier saved on the inserted token. If omitted, RichText generates an ID automatically
+- `label` - (required) the text shown in the dropdown and inserted into the document


not really required, u can use custom template (for example: triggerTemplate: template(({data}) => data.id))

Done. label is now marked (optional), with a note that it is required only for the default rendering — with a custom triggerTemplate you can render from other fields (e.g. template(({ data }) => data.id)) and omit it.

DmitriySlabodchikov · 2026-06-03T16:34:56Z

+
+### Custom action
+
+By default, when a user picks an item, RichText inserts it into the document as a token. Set the `action` parameter to run your own code instead: RichText removes the typed trigger string (the trigger character and the query) and calls the `action(item)` callback with the picked item. No token is inserted, so you can decide what to add to the document. The `action` parameter takes priority over `showTrigger`. When `action` is set, `showTrigger` is ignored.


so you can decide what to add to the document or don't add anything at all, but call your custom code

Done. Reworded: "No token is inserted, so you can decide what to add to the document (or run your custom code)."

DmitriySlabodchikov · 2026-06-03T16:41:44Z

+        {
+            trigger: "@",
+            data: [
+                { id: "alice", label: "Alice", url: "mailto:alice@example.com" },


url: "mailto:alice@example.com"

so ctrl-click automatically launches your default email client (like Gmail, Outlook, or Apple Mail) and prefills a new email draft with the recipient's address

Done. Added a note under the example: because the @ items use a mailto: value, Ctrl+Click on the token launches the default email client (Gmail, Outlook, Apple Mail, …) and opens a new message pre-filled with the recipient address.

kullias · 2026-06-03T18:18:26Z

 ### Suggestion item fields

-Each item in `data` (or each item returned by a function) has the following fields:
+Each item in the `data` object (or each item returned by a function) has the following fields:


data is not an object, it's an array or a function that returns an array (so the previous description was correct and all that's above too. returning the old wording is enough, no need to repeat again that it's an array or a function)

kullias · 2026-06-03T18:25:43Z

+    return String.fromCodePoint(parseInt(code, 16));
+}
+
+const emoji = [


should be declared before it's read in line 158. if a user copies this code and pastes, this will throw. if I understand correctly, you moved it to make the snippet better readable - understandable, but alas. shorten the emoji array, that would make the snippet neater, and move it before line 154.

- mark suggestion `label` as optional (custom triggerTemplate case) - note Ctrl+Click opens token url, explain mailto behavior - break down rendered token attributes (trigger/id/url/label) - clarify custom action can run code without inserting content - add "Group emoji by category" example with custom filtering, category headers and api.intercept guard - triggerTemplate: add second trigger so trigger check is meaningful, replace !important width tip with more specific selector

serhiipylypchuk1991 added 11 commits May 27, 2026 09:16

[add] hide-suggest event docs

3d4da9d

- new API reference page for the hide-suggest event - documents when the dropdown closes (selection, Escape, cursor leaves trigger, empty result)

[add] insert-token event docs

6eac577

- new API reference page for the insert-token event - documents callback fields (id, label, url, trigger, showTrigger)

[add] show-suggest event docs

34f4c79

- new API reference page for the show-suggest event - documents callback fields (trigger, query, items, pos) and intercept example

[add] triggers config docs

44b66d8

- new API reference page for the triggers property - covers static array, sync function, async function data sources - documents suggestion item fields and rendered token CSS targeting

[add] triggerTemplate config docs

a49929b

- new API reference page for the triggerTemplate property - documents callback parameters (data, trigger) and template usage - includes tip on overriding the dropdown anchor width

[add] Mentions and tags guide

d1adb47

- new guide covering trigger characters, data source forms, token rendering, and event handling - examples for static array, sync function, async function, and custom dropdown templates

[update] add suggestion events to events overview

6948c9c

- list hide-suggest, insert-token, and show-suggest in the events table

[update] add trigger configs to properties overview

ce748b7

- list triggers and triggerTemplate in the properties table

[update] mention triggers in configuration guide

90c074d

- list triggers in the property overview with a link to the Mentions and tags guide

[fix] correct anchor for custom toolbar controls link

d764692

- update anchor in whats_new from #custom-toolbar-controls to #add-custom-toolbar-controls to match the heading in configuration.md

[update] register trigger pages in sidebar

f888bf7

- add hide-suggest, insert-token, show-suggest under events - add triggers and trigger-template under properties - add mentions_and_tags under guides

serhiipylypchuk1991 self-assigned this May 27, 2026

serhiipylypchuk1991 requested a review from kullias May 27, 2026 11:48

kullias requested changes Jun 2, 2026

View reviewed changes

serhiipylypchuk1991 added 2 commits June 3, 2026 18:27

[update] align insert-token handler in guide

2f2a6b7

- destructure ({ data, trigger, showTrigger }) to match the insert-token event docs and the PR review suggestion

DmitriySlabodchikov reviewed Jun 3, 2026

View reviewed changes

kullias reviewed Jun 3, 2026

View reviewed changes


		#### Add emoji

		A common use case is inserting an emoji from a `:` trigger, where each item contains a custom `code` field. Pair `action` with [`triggerTemplate`](api/config/trigger-template.md) so the dropdown shows the emoji itself instead of just its label:


		### Custom action

		By default, when a user picks an item, RichText inserts it into the document as a token. Set the `action` parameter to run your own code instead: RichText removes the typed trigger string (the trigger character and the query) and calls the `action(item)` callback with the picked item. No token is inserted, so you can decide what to add to the document. The `action` parameter takes priority over `showTrigger`. When `action` is set, `showTrigger` is ignored.

Conversation

serhiipylypchuk1991 commented May 27, 2026

Uh oh!

kullias left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DmitriySlabodchikov Jun 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DmitriySlabodchikov Jun 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

DmitriySlabodchikov Jun 3, 2026 •

edited

Loading

DmitriySlabodchikov Jun 3, 2026 •

edited

Loading